/* Define to prevent recursive inclusion -------------------------------------*/
 /* This preprocessor directive establishes an include guard to prevent multiple */
 /* inclusions of the same header file during the compilation process, which */
 /* would cause redefinition errors and compilation failures */
#ifndef __LOG_MANAGE_H
#define __LOG_MANAGE_H

/* Standard integer type inclusion for portable type definitions */
/* Provides uint8_t, uint16_t, etc. for consistent data sizing across platforms */
#include <stdint.h>

/**
 * @brief Comprehensive log level enumeration for message severity classification
 * This enumeration defines a hierarchical system of log message severities
 * that allows for filtered output based on application debugging requirements
 * and operational verbosity settings
 */
typedef enum
{
  /* Most verbose logging level for detailed diagnostic information */
  /* Typically used for tracing program flow and variable state tracking */
  MSG_VERBOSE,
  
  /* General informational messages for normal operational status */
  /* Used for reporting significant application state changes and milestones */
  MSG_INFO,
  
  /* Debug-level messages for development and troubleshooting purposes */
  /* Contains information useful for developers during testing phases */
  MSG_DEBUG,
  
  /* Warning messages for non-critical issues that don't halt execution */
  /* Indicates potential problems that should be investigated but don't */
  /* necessarily represent immediate functional failures */
  MSG_WARNING,
  
  /* Error messages for critical failures that affect system functionality */
  /* Represents serious issues that require immediate attention and may */
  /* impact the correct operation of the application or system */

} logLevelEnum;

/**
 * @brief Formatted logging output function with variable argument support
 * This is the primary logging interface that provides printf-style formatting
 * capabilities combined with log level filtering and timestamp generation
 * @param level: Log level enumeration value determining message severity
 *               and filtering priority according to the logLevelEnum definition
 * @param fmt: Format string specifying the structure and content of the log
 *             message using standard printf-style format specifiers
 * @param ...: Variable argument list containing values to be formatted according
 *             to the specifications in the format string parameter
 * @return void: This function does not return a value but outputs to the
 *               configured logging destination (file, console, etc.)
 */
extern void log_printf(logLevelEnum level, const char *fmt, ...);

/**
 * @brief Initialize the logging subsystem and prepare for log message processing
 * This function performs the necessary setup operations to establish the
 * logging infrastructure, including file handle creation, configuration
 * validation, and resource allocation for log message storage and output
 * @return uint8_t: Returns TRUE if logging initialization completed successfully,
 *                  FALSE if any initialization step failed, indicating that
 *                  the logging system may not be available for use
 */
extern uint8_t log_manageInit(void);

/**
 * @brief Safely shutdown the logging subsystem and release allocated resources
 * This function ensures proper cleanup of logging resources including file
 * handle closure, buffer flushing, and memory deallocation to prevent
 * resource leaks and data corruption during application termination
 * @return void: This function does not return a value but guarantees that
 *               all logging resources are properly released and any pending
 *               log messages are flushed to their destination
 */
extern void log_closeFile(void);

#endif /* __LOG_MANAGE_H */